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PREFACE 


Transaction processing in the Multics system can be performed by the 
subsystem described in this manual. By employing the transaction processing 
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manual describes the Multics TP subsystem, describes the administrative commands 
and their usage, and furnishes the practical details of subsystem operation. 
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MULTICS TRANSACTION PROCESSING 


The Multics transaction processing (TP) subsystem provides a specialized 
environment for applications requiring much activity with a few centralized 
databases. Within the subsystem only a limited, well-defined set of simple 
commands are available. Most of these are application programs that interact 
with a database. The TP user is isolated from the general Multics interactive 
environment. In this manual, a user is a person who enters transactions from a 
terminal. He is not expected to know about computers. People who write the 
application programs are Multics users but not necessarily TP users. Many 
aspects of the subsystem are table-driven or specified in modifiable modules, so 
that features can easily be added, changed or deleted. Several independent TP 
subsystems may run concurrently on a single Multics system. 


This manual describes how the Multics TP subsystem is organized, how to run 
it, how to meter it, and how to write application programs for it. However, 
both administrators and application programmers may still need to consult 
various volumes of the MPM, as well as other appropriate manuals for further 
information concerning the Multics system and its use. Specific TP user 
requests are site-dependent and therefore are not included. 


Features available in the Multics TP subsystem include the following: 


® locking of individual database records to allow concurrent database 
access 

® commitment and rollback facilities which allow handling of both 
concurrency control = and restoration after an error or. other 
interruption 

® availability of most Multics languages for application programs 

* modular construction to facilitate tailoring of the system 

 ) separation of input/output nvrocessing and computaticn to allow better 
tuning 

a a deadline mechanism for scheduling transactions 


easily established parallel environments for testing application 
programs 


1-1 CC96 


OVERVIEW OF STRUCTURE 


For the purpose of discussion within this manual, a transaction is defined 
as the processing of a single user command, from receipt of the input message by 
the TP subsystem to execution completion. A transaction processing routine 
(TPR) is an application program. It usually is one that references a large 
database. 


A transaction is a series of modifications to a database that appear to 
occur atomically and simultaneously to other processes. To ensure that all 
database changes will appear at the same time, the changes made by a TPR are not 
visible to other processes’ until the transaction is finished. When a 
transaction is finished, the TP subsystem automatically performs an operation 
called a commitment. A commitment means that this transaction is finished, and 
all changes to the database since the last commitment should be made visible to 
other processes. This scheme ensures database consistency. Occasionally a 
commitment by one process changes data that a transaction in another process 
depends upon. This is called an asynchronous change. The second process may 
then have an inconsistent view of the database. A commitment by the second 
process under’ these circumstances will fail. When this happens, the TP 
subsystem rolls back the transaction. This means that all changes made to the 
database since the last commitment are erased. The transaction usually will be 
retried. 


The Multics TP subsystem is organized to make efficient use of resources by 
taking advantage of the special characteristics of TP. Typically, many users 
are all performing similar operations ona fixed set of databases, using a 
closed environment of their own rather than the standard Multics command 


wee wae ws Wad aa Coie awe 
environment. 


Allocating a process per user would entail much duplicated address space 
overhead and would be difficult to schedule efficiently. Therefore, the TP 
subsystem's processes are organized differently. They are divided according to 
function into the following three types: 


@ Master process--coordinates and communicates with the other processes 
I/O process--manages input from and output to terminals 
e Worker process--executes the application programs 


A TP subsystem consists of one master process, one or more I/O processes, and 
one or more worker processes. 


The I/O and worker processes communicate with each other via the input and 
output queues as well as through a_ shared table. The input queue contains 
commands to be processed, and the output queue contains output from TPRs. 
Figure 1-1 shows a simplified diagram of the relationships of the various 
processes. These processes are described in more detail below. 
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Figure 1-1. Structure of the Multics TP Monitor 
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The master process is used by the TP administrator to begin transaction 
processing. First the master table is initialized. Then the master process 
logs in all of the other processes. No explicit action is taken if the TP 
subsystem is being restarted after an abnormal interruption. In that case, any 
database modifications that were incomplete are automatically rolled back as 
they are encountered in normal processing. The master’ process is responsible 
for coordinating TP shutdown. This includes ensuring that all transactions in 
progress are completed. 


An I/O process handles input/output for a group of terminals. The lines 
handled may be dedicated or attached to the I/O process’ by the dial facility. 
This process also queues and schedules input messages. Transactions” are 
scheduled by deadlines. A deadline is a date-time associated with the 
transaction. Of two transactions in the input queue at the same time, the one 
with the earlier deadline will be started first. No attempt is made to execute 
a transaction by the time indicated as its deadline. Some commands that require 
little processing and do not involve database references may be executed by the 
I/O process. These are called immediate commands. 


A worker process executes one transaction at a time. Output messages to be 
printed on the user's terminal are placed into the output queue. Databases are 
accessed through the standard file I/O module, vfile , in a mode that allows 
changes to reversed if a transaction is interrupted because of an error or 
system crash. Also, if a transaction fails because of a concurrent update to 
the database by another process, the changes are rolled back and the transaction 
is re-executed. All databases to be referenced are attached and opened at the 
beginning of the process to reduce overhead for individual transactions. 


SECURITY 


I/O and worker processes may have different User ids so that Multics access 


control may be used to restrict database access to worker processes. Individual 
users, however, are not logged into Multics while using the TP subsystem; in 
fact, they need not be registered Multics users at all. They only need to be 


registered as TP users by the TP administrator. Signing on to the TP subsystem 
is handled by the I/0 processes and involves only the TP subsystem's person-name 
table. Since the set of commands users can invoke is restricted (e.g., editors 
or compilers are generally excluded), individual TP users are unable to perform 
malicious acts. 


USER INTERACTION 


The TP user types input request lines, which cause TPRs to be run. The 
TPR's output is. printed on the terminal. The input line is’ read by an I/0 
process and the TPR is executed in a worker process. Figure i-2 shows 
conceptually how a transaction is processed. The transaction input is read from 
the terminal and placed into the input queue. Some worker process then finds 
the transaction in the input queue and invokes the appropriate TPR. Any output 
written by the TPR onto the user output I/0 switch is placed into the output 
queue. An I/O process then prints output from the output queue on the user's 
terminal. 
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Figure 1-2. How a Transaction is Processed 
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A user may wait for the complete output from a_ transaction to be printed 
before typing the next transaction. However, the TP subsystem does not enforce 
serial execution. If the user enters transactions without waiting for previous 
ones to complete, the following things may happen. The output from an immediate 
command usually appears before output from any other pending transaction. This 
is because immediate commands are executed as soon as they are read rather than 
queued for a worker process. The output from a regular transaction might not be 
contiguous and might appear before the output from a transaction entered 


earlier. Aside from deadline considerations, this may occur because the TP 
subsystem can execute more than one transaction from a single user 
Simultaneously. Although execution of transactions is in deadline order, a 


later transaction may finish before an earlier transaction. In addition, the 
output messages are queued as soon as they are generated, not when the TPR 
finishes. 


Since output messages from one transaction may be interspersed with output 
messages from other transactions, each output message is labeled with the 
transaction number. The transaction number is printed when a transaction is 
queued. 
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A Multies TP subsystem 
contained in it. Following 


segments. 


Control Segment 


tp_master_ table 


tp command table_ 


tp_init_database.ec 


tp_person_name_ table_ 


tp_start_up.ec 


worker start _up.absin 


io start_up.absin 


tp.tpoutq 


SECTION 2 


RUNNING AND OPERATION 


is defined by a directory and the control segments 
is a list and brief description of the control 


Description 


contains most of the dynamic information used by 
the TP processes. This includes information about 
each terminal, each process, and interprocess 
communication information. 


lists the valid command names for the TP subsystem 
and their associated attributes. See the 
description of the tp_cvsct command. 


contains commands to open and initialize MRDS 
databases. This segment is needed only if MRDS is 
used. 


contains the names of registered TP users” and 
their encrypted passwords. See the description of 
the tp_user command. 


Starts transaction processing and starts up the 
I/0 and worker processes via Multics 
enter_abs request commands. 


is the worker process absentee control segment 
which initializes the non-MRDS databases to be 
used by the worker and then turns the process into 
a worker. 


is the I/O process absentee control segment which 
turns the process into an I/O process, passing it 
Slave channel names and/or a dial id. 


is the transaction control file and contains 
information indicating whether database operations 
have been committed. See Section 4. 


is the input queue and contains, for each queued 
transaction, its input command line, meters, 
information about its output destination, and its 
current state. 


is the output queue and contains the transaction 
output messages to be displayed on terminals. 
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SETTING UP A TP SUBSYSTEM 


The following discussion presents the considerations required to set up a 
TP subsystem, and lists the necessary procedural steps. To illustrate each 
step, an example of atypical transaction processing situation, called the 
Sample TP project, is also included. In this discussion, reference is made to 
access control lists (ACLs) and setting of access to segments. See "Access 
Control" in the MPM Reference Guide for a discussion of the various kinds of 
access. 


The TP Administrator 


TP administrator is the term used in this manual for the person who 
performs the following tasks: 


® creating subsystem directories and tables 
+] Starting, stopping, and monitoring transaction processing 
® making sure databases are consistent after crashes 


User ids for a TP Subsystem 


All I/O processes should use one given User_id. Likewise, all worker 
processes should use some other User id. 


The master, I/0, and worker processes should all have User_ids different 
from each other for security reasons. The Sample TP project has the following 
User ids: ~ 


Process User id 
Master Process Master.Sample TP 
I/O Processes IO0.Sample TP 


Worker Processes Worker.Sample TP 
TP administrator PCJones.Sample TP 


TP Process Names 


Each I/O and worker process is. given a unique name to identify it within 
the TP subsystem. This name is independent of the User id of an I/O process or 
a worker process. The process name is also the first component of the absentee 
control segment for an I/0 or worker process. In the Sample TP project, there 
will be three I/O processes named IO 1, I0 2 and IO 3. There will be two worker 
processes named Worker_1 and Worker _ 2. a + 
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Set-Up Procedure 


Following is a list of the steps necessary to establish a TP subsystem: 


1. 


Register the User ids for the TP administrator, master, I/O and worker 
processes. The I/0 and worker processes' User ids should have 
max foreground set to the maximum number of concurrent I/O and worker 
processes, respectively. If the dial facility is used, the I/0 


process User id should be given the dialok attribute. (See the 
Muitics Administrators! Manual -- Project Administrator, Order 
No. AK51, for information about registering User ids.) For the 
sample TP. project, the following User ids .-are registered: 
PCJones.Sample TP, Master.Sample TP, ~ I0.Sample_TP and 


Worker.Sample TP. 


Arrange to have the master process be given execute (e) access to the 
proxy ACS. This enables it to log in absentee processes for the other 
processes. For the Sample TP project, the system administrator issues 
the following command: 


Sa >system_control 1>proxy>absentee proxy.acs e Master.Sample TP 


Create the TP subsystem's directory. This is the directory in which 
all the control segments reside. The master process and TP 
administrator should have sma access to this directory. The I/O and 
worker processes should not have modify access, but should have status 
and append access tO. it, In the Sample TP project, the TP 
administrator issues the following commands: > 


create dir >udd>Sample TP>tp dir 

change wdir >udd>Sample TPS tp. dir 

set_ acl [wd] sma Master. Sample TP sa I10.Sample TP 
sa Worker. Sample TP 


The following commands assume the working directory is 
>udd>Sample TP>tp dir. 


Create a subdirectory for the commands. -This must be named 
"commands". The I/O and worker’ processes should have s access to it. 
The master process should have sma access. In the Sample TP project, 
the TP administrator issues: 


create dir commands 
set acl commands sma Master. Sample TP s 10.Sample TP 
s Worker. Sample TP 


Create the master table with appropriate access. All processes should 
have rw access to it. The TP monitor will enlarge it. For the 
Sample TP project: 


create tp master table 
set acl tp_ master table_ rw Master.Sample TP rw I0.Sample TP rw 
Worker. Sample_ TP 


Create the transaction control file (TCF) with appropriate access. 
All processes should have rw access to it. The tp_ pre_create exec _com 
makes sure the transaction control file is a multisegment file. The 
TCF should never be deleted. 


ec >unb>tp pre create tp.tcf 


set_acl tp.tef rw Master.Sample TP rw 10.Sample TP rw 
Worker.Sample_ TP 
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10. 


Create the input queue with appropriate access. All processes should 
have rw access to it. For the Sample TP project: 


ec >unb>tp pre create tp.tping 
set acl tp.tping rw Master. Sample TP rw IO0.Sample TP rw 
Worker. Sample TP 


Create the output queue with appropriate access. All processes should 
have rw access to it. For the Sample TP project: 


ec Dunb>tp pre create tp.tpoutq 
set acl tp.tpoutq rw Master. Sample TP rw 10.Sample TP rw 
“Worker. Sample TP 


Create the I/O process absentee control segment, io_start_up.absin, in 
the TP directory. Each I/O process should have r access to it. For 
each I/O process name, I0 process name, io start up.absin should have 
the additional name IO process name.absin. The absentee segment 
requires one argument, the pathname of the TP directory. The I/0 
process absentee control segment should be’ similar to the following 
one for the Sample TP project: 


change wdir &1 


& 

& To protect this process against being logged out due to 

& inactivity, uncomment the next three lines. 

& memo -pathname &ec name -on 

& memo -delete -match nothing 

& memo -time "20 minutes" -repeat "20 minutes" -alarm -call 
nothing 

& 

&goto &ec_name 

& 

&label IO 1 

tp_io start &ec _name [wd] channel1 channel2 channel3 

&quit 

& 

&label I0 2 

tp_io start &ec _name [wd] -registered dial Sample TP_system 

&quit 

& 

&label IO 3 

tp_io_start &ec_ name [wd] channel4 channel5 -dial TP system 

&quit 7 

Create tp init database.ec. This segment is needed only if the 


Multics Relational Data Store (MRDS) is used. Each worker process 
must have r access to this segment. This exec com contains commands 
to prepare a MRDS database for use. It is invoked when the run unit 
in which TPRS execute is started. The following is the format of a 
typical tp init database.ec. 


& Prepare MRDS databases 
mrds_call open dsm_paths 
mrds_ call set_tef switch [mrds get_dbi (dsm_paths)] tcf_ 
mrds_ call ready file [mrds get dbi dsm pathT] 
file name rdy | model... file namei rdy modei 
mrds_call set collection _delay_ time [mrds _get_ dbi dsm _pathi] 
file name1 delay_ timel 


mrds_ call set collection delay time [mrds get _dbi dsm_path1] 
file_ namei delay_ timei 


mrds_call ready file [mrds get dbi dsm_pathn] 
file_namel rdy_ model ... file namej rdy_modej 
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mrds_call set collection delay time {mrds _get_dbi dsm | pathn] 
file name 1 delay_ time1 


mrds_call set collection delay time [mrds get _dbi dsm_pathn] 
file namej delay timej 
&quit 


To ensure repeatability if an asynchronous change occurs, only the 
monitor retrieve or update ready modes should be used. The collection 
delay time should be longer than the real time any transaction that 
uses the file will require. The following is tp init database.ec for 
the Sample TP project: ~ 


& Prepare MRDS databases 

mrds call open <databases>people db <databases>inventory 

mrds- call set tef switch [mrds get_ dbi (<databases>people__ db 
<databases>inventory)] tef 

mrds_ call ready file [mrds get dbi <databases>people_ db] 
people monitor retrieve 

mrds_ call set collection | _delay time [mrds _get_dbi <databases> 
people db people 90] __ 

mrds_ call ready file [mrds get_dbi <databases>inventory] 
inventory update 

mrds call set collection delay time [mrds _get_dbi <databases> 

~ inventory inventory 300] 


&quit 
Create the worker process absentee control segment, 
worker start_up.absin, in the TP directory. Each worker process 
Should have r access to it. For each worker process name, 


worker process name, worker start _up.absin should have the additional 
name worker_process name.absin. The absentee control segment requires 
one argument, the pathname of the TP directory. All segments in the 
commands directory are explicitly initiated to reduce overhead. All 
files accessed through language I/O facilities or through iox 
directly should also be attached and opened with io call to eliminate 
this overhead from TPRs. The worker process absentee control segment 
Should be similar to the one for the Sampie TP project: 


change wdir &1 

initiate commands>([segments commands>**] [links commands>#**]) 
-all -force 

tp_worker init tef [wd] 

& 

& Attach and open I/O switches 

io _ call attachparts vfile_ <databases>parts -stationary 
-transaction tef -share 

io call open parts keyed sequential update 

io call control parts set_wait_time -collection delay time 300 

& 

To protect this process against being logged out due to 

Inactivity, uncomment the next three lines. 

memo -pathname &ec_name -on 

memo -delete -match nothing 

memc ~time "20 minutes" -repeat "20 m 


nothing 


Re Re Re Re Ro 


& 
tp_worker start é&ec name [wd] 
&quit 


For a file that is attached above to be protected by the commitment 
mechanism, the vfile attach description must include "-stationary 
-transaction tcf_ -share". The collection delay time should be longer 
than the real time any transaction that uses the file will require. 
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Create the TP subsystem's start up exec com, tp_start_up.ec. The 
master process should have r- access to it. The exec com requires one 
argument, the pathname of the TP directory. The tp start up.ec 
segment should be similar to the one for the Sample TP project: ~ 


&command line off 

&if [nequal &n 1] 

&then &goto start 

&print Usage: ec tp start up tp dir 
&quit a i ~ 

& 

&label start 

change wdir &1 


answer yes -brief do """rename &(1) [strip _entry &(1)].old.absout"™ 


(Lsegments *.absout]) 
tp_start [wd] 
& 
ear IO_1 -foreground -proxy I0.Sample TP -arguments [wd] 
ear I0 2 -foreground -proxy I0.Sample TP ~-arguments [wd] 
ear I0 3 -foreground -proxy I0.Sample TP -arguments [wd] 
& ze 
ear Worker_1 -foreground -proxy Worker.Sample TP -arguments [wd ] 
ear Worker 2 -foreground -proxy Worker.Sample TP -arguments [wd] 
&quit 


Create tp command table . See the description of the tp cvsct 
command. The master, worker and I/O processes should have r access to 
it. This segment lists all commands, including I/O process immediate 
commands, that TP users may type. 


Write the transaction processing routines (TPRs). See Section 6. Put 
all TPRs, or links to them, in the "commands" directory contained in 
the TP directory. I/O processes must have re access to commands that 
they can execute. Worker processes must have re access to commands 
that they execute. 


Create tp person name table . The master process’ should have rw 
access to it, the worker and I/O processes should have r access to it. 
For the Sample TP project: 


create tp person name table 
set_acl tp_person_ name table rw Master.Sample TP 
r I0.Sample TP r Worker.Sample TP. 


Prepare and distribute TP user documentation. 


Use the tp user command to enter TP users and their passwords into 
tp_person_ name table . 


Create all databases needed by the worker’ processes. All keyed 
Sequential vfiles must be multisegment files before transaction 
processing is started. The tp pre create exec _com creates an empty 
multisegment keyed sequential vfile. Worker processes must have 
access to the databases they will use. See the MRDS Reference Manual, 
Order No. AW53, for information about initializing MRDS databases. 
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A Complete TP Subsystem 


After setting up the TP subsystem for the Sample TP project, a listing of 
the TP directory is as follows: 


Segments = 7, Lengths = 9. 


r ow 3 tp person name table_ 
row 2. tp. command __ table_ 
r ow 1 tp_ start up.ec 
row 1 worker start’ up.abSsin 
Worker 1.absin 
Worker 2.absin 
row 1 tp init database.ec 
row 1 io start up.absin 
IO 1.absin 
IO 2.absin 
IO 3.absin 
row O tp master_table_ 


Multisegment-files = 3, Lengths = 21. 


row 7 tp.tpoutq 
row 7 tp.tping 
r ow t: tpcter 
Directories = 1. 


sma commands 


OPERATING A TP SUBSYSTEM 


This section describes how to run a TP subsystem once it has been set up. 
It also describes how to attach terminals to the TP subsystem. 


Starting Transaction Processing 

To start transaction processing, log in the master process and issue the 
following command in the master process: 

ec tp start _up tp dir 


where tp dir is the pathname of the TP directory. For the Sample TP project the 
command would be: 


ec tp_start_up >udd>Sample TP>tp dir 


In tp_start_up.ec, the tp start command turns the process into a master process. 
The 170 and worker processes are then logged in. 


Managing Transaction Processing 


If another I/O process or worker process is required after transaction 
processing has started, an enter abs request command similar to the ones in 
tp_start_up.ec can be issued in the master process. The I/O or worker process 
name of the new process must not be the same as an existing process's name. 
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If the master process should be destroyed while transaction processing is 
running, invoke the tp start command with the -new_master control argument to 


establish another process as the master. process. Periodically a program 
automatically runs in the master process and makes’' sure all the I/O and worker 
processes still exist. If one has been destroyed, a message is printed and an 


enter abs request command is automatically issued to restart it. If an I/0 
process is destroyed and restarted, all TP users that were connected to it must 
sign on again. Check the I/O and worker process's absentee output segments for 
error messages, 


Shutting Down Transaction Processing 


Transaction processing is shut down by issuing the tp stop command in the 
master process; the rest is done automatically in two stages. In the first 
Stage, the I/O processes stop accepting input and the worker processes either 
finish all pending transactions or, if the -immediate control argument was 
specified, just finish their current transactions. The worker processes then 
log out. In the second stage, the I/O processes finish processing all 
accumulated output and log out. Thus, when a shutdown is complete all the 
output from completed transactions has been processed. If the -immediate 
control argument was specified, there may be some transactions left in the input 
queue to be processed when transaction processing is resumed. A message is 
printed by the master process when the shutdown has completed. 


Input Queue Maintenance 


The input queue may be placed on a different logical volume than the 
databases used by the TP subsystem. In this case, the TP directory should 
contain a link to the input queue. 


As transactions are entered into the TP subsystem, they are placed into the 
input queue where worker processes obtain transactions to execute. When a 
transaction is finished, its entry is not deleted from the input queue. 
Instead, the entry is changed to indicate that the transaction has completed. 
The input queue therefore keeps getting larger. Several things can be done to 
keep the input queue from growing indefinitely: 


e The tp shrink q command may be used to delete records from the input 
queue. This may be done while the TP subsystem is running. Records 
may be copied to any device. Records of successful transactions may 
be separated from those of unsuccessful ones. 


. The input queue may be renamed. This should only be done when the TP 
subsystem is not running and there are no pending transactions. Using 
this method, a different multisegment file may be used each day as the 
input queue. The tp meters command may be used to obtain statistics 
from a previous input queue. The old input queues may be deleted or 
copied to a backup device as needed. A new input queue must be 
created before resuming transaction processing. 


e The input queue may be deleted. This should only be done when the TP 
subsystem is not running and there are no pending transactions. This 
method naturally leaves no record of processed transactions. A new 
input queue must be created before resuming transaction processing. 
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Dial and Terminal Use 


In Multics TP, each I/O process manages a group of terminals. It is not 
possible for a particular terminal to be used by more than one process at a 
time. An I/O process handles all the input and output for its terminals 
including user signons. Terminals are connected to an I/O process either 
through the dial facility or through specified siave channeis. The i/0 process 
controls the terminals and therefore controls the users' access to Multics and 
to the TP subsystem. A TP user need not be a registered Multics user. 


Use of the Dial Facility 


The Multics dial facility allows several terminals to be attached to the 
Same process. A terminal is connected to an existing process by the dial access 
request. (See MPM Commands, Section 4 for a description of the dial access 
request.) In order for an I/O process to accept dials, the tp io start command 
must be given the -dial or -registered dial control argument. See the 
description of tp io start in Section 3 of this manual. 


The dial facility should be used when there are login service type channels 
that use the TP subsystem, i.e., when some channels need to be able to access 
the TP subsystem at some times and to log in to Multics at other times. 


Use of Slave Channels 


An I/O process may manage channels that are specified when the command 
tp_io_ start is invoked. These channels must be of the slave service type. See 
the Multics Administrators' Manual -- Communications Order No. CC75, for a 


description of the channel definition table (CDT), the slave service type, and 


for instructions on using the slave service type. 


RUNNING TP IN TEST ENVIRONMENTS 


Parallel TP subsystems may be used for’ testing. Setting up atest 
subsystem requires creating a directory and the necessary control segments, just 
as for a real TP subsystem. If databases are used in common with another TP 


Subsystem, the TP subsystem's transaction control file must also be used via a 
link in the test TP directory. 


Establishing Test Processes 


Once a test environment has been created, test processes must be set up. 
Any process with access to the test TP directory and control segments can he 
used. One way is to use special test Person_ids within the TP project. Once 
tp start has been invoked in the test TP subsystem's master process, the I/O and 
worker processes can be logged in. A process becomes an I/O or worker process 
by invoking the tp_io_ start or tp_worker_ start commands, respectively. The test 
processes can be interactive or foreground absentee processes. However, an 
interactive worker process will require a terminal that it ignores. 


One process may, with restrictions, serve more than one function within the 
TP subsystem. If one process is serving as both the master process and an I/0 
process, and the terminal is connected to the TP subsystem, then the command 
table must contain any desired master process commands as immediate commands. 
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Combining the master process and a worker process is not recommended because a 
worker process ignores all input from the terminal. An interactive process may 
serve as an I/O process and a worker process. In this case, the tp io start 
command must precede the tp worker start command, and the terminal may not be 
connected to the TP subsystem. = 


Test Mode 


Any user may use a TP subsystem in test mode. Transactions are processed 
and produce output in test mode but databases are not changed. To enter this 
mode, use the tp io enter test mode immediate command. To return to normal TP 
processing, use the tp_io_exit_test_mode immediate command. 


See Section 3 of this manual for descriptions of the transaction processing 
commands mentioned in the preceding paragraphs. 
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mrAt 


TP COMMANDS AND SUBROUTINES 


The commands and subroutines available to the user and TP administrator for 
transaction processing are described in this section. They are presented in a 
format consistent with that described in the Multics Programmers' Manual (MPM). 


The TP commands and subroutines may be classified according to the context 
in which they may be invoked. The contexts in which a TP command or subroutine 
may be invoked are: 


® in the master process 

e in the worker process 

e in the I/O process 

* outside the TP subsystem or in the master process 


The commands and subroutines are described in four subsections, according 
to the context in which they are invoked. Within each subsection, the commands 
and subroutines are presented alphabetically. The following is an alphabetical 
list of all the commands and subroutines described in this section together with 
designation of the context in which they may be invoked. 


Command or Subroutine 


tp_ cancel 
tp_change deadline 


Context 


master process 
master process 


a dae outside TP 
tp_ display command table outside TP 
tp_ display_ current_ xens master process 
tp_ display_ input _ queue outside TP 
tp_ display_ master table outside TP 
tp_ display. _output _ queue outside TP 


tp_ get xen status — 

tp_ io _cancel 

tp. io enter test mode 

tp io _exit_ test mode 

tp io _get_ xen status 

tp io _list _pending | requests 
to io “signoff 


master process 
I/O process 
I/O process 
I/O process 
I/O process 
I/O process 
TIN nmn 


AA 
hse Del ccess 


tp_io_start I/O process 
tp_io who I/O process 
tps, list _pending requests master process 
tp_ "meters outside TP 

toe pre _create.ec outside TP 

tp. reset xen num outside TP 

tp_ rollback _ transaction _ worker process 
tp_ shrink q_ outside TP 

tp start — master process 
tp_stop master process 
tp user outside TP 


tp_verify transaction_ 


worker process 
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tp_who master process 
tp_worker_init tcf worker process 
tp_worker start worker process 
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MASTER PROCESS COMMANDS 


This subsection contains descriptions of commands that may only be invoked 
in the master process. The master process commands are presented in 
alphabetical order within this subsection and include the following: 


tp cancel 

tp change deadline 

tp display current xens 
tp get xen status _ 

tp list_pending requests 
tp start 

tp stop 

tp_who 


3-3 CC96 


tp_cancel tp_cancel 


Name: tp cancel 


The tp cancel command removes one or more transactions from the input queue 
to prevent them from being processed. The transaction must not have started 
executing. 


Usage 
tp_cancel transaction _nums 


where transaction nums are the numbers of the transactions to be canceled. 
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tp change deadline tp_change deadline 


Name: tp change deadline 


The tp change deadline command changes the deadline of the specified 
transaction. The transaction must not have started executing. 


Usage 


tp_change deadline transaction num DT 


where: 

1. transaction num 
is the transaction number of the transaction whose deadline is to be 
changed. 

2. DT 
is the new deadline time of the transaction. It is a string 


acceptable to the convert _date_to binary subroutine described in 
the MPM Subroutines. 
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tp_display current _xcens tp_display current xcns 


Name: tp display current xcns, tpdex 


The tp_ display current xens command prints information about the 
transactions currently executing. The worker process name, transaction number, 
TP command name and TP_user_id are printed. 


Usage 


tp_display current xens 
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tp get_xen_status tp_get_ xen status 


Name tp get xen status, tpexs 
The tp get xen status command prints information about one or more 
transactions. If the transaction has not yet been processed, the TP user id of 


the TP user who submitted it, the TP command name, its deadline, its position in 
the queue and the time it was submitted will be printed. If the transaction is 
currently being processed, the above information and the time it was started are 
printed. If the transaction has finished, except possibly for output, all the 
above information, the time it finished, whether there were any errors, real and 
cpu time used, page faults, and total real time, not including output processing 
are printed. 


Usage 


tp_get_xcn_status transaction _nums {-control arg} 


where: 
1. transaction nums 

are the transaction numbers of the desired transactions. 
ae control arg 


may be -brief or -bf to cause only the state of the transaction to 
be printed. 
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tp_list_ pending requests tp_list pending requests 


Name: tp list pending requests, tplpr 


The tp list pending requests command lists the transactions that have not 
been completed. 


Usage 


tp_list_pending requests {-control args} 


where control args may be chosen from the following list: 


-total, 


-long, 


-tt 
prints only the total number of pending transactions for’ the TP 
subsystem and for each TP user. 


-lg 

prints the transaction number, deadline, time submitted, position in 
the queue, and the user's TP user id of each pending transaction. 
The default is to. print the transaction number and the position in 
the queue. 


-before DT, -be DT 


prints information about transactions with deadlines before the 
specified time. DT is a string acceptable to the 
convert date _to binary subroutine described in the MPM Subroutines. 


-after DT, -af DT 
prints information about transactions with deadlines after the 
specified time. DT is a string acceptable to the 
convert date to_binary subroutine described in the MPM Subroutines. 
-user STR 


prints information only about transactions for the TP user whose 
TP_user_id is specified by STR. 
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tp_ start 


Name: tp start 


The tp_start command starts transaction processing by initializing the TP 
master table. The process it is used in becomes the master process. 


Usage 


tp start path {-control arg} 


where: 

1. path 
is the pathname of the directory that contains the control segments 
for the TP subsystem. 

2s control arg 


may be the following: 


—-new master 
“to make the current process the master process of a running TP 
subsystem. This should be used if the original master process is 
destroyed while the TP subsystem is running. 


Notes 


The subsystem databases, transaction control file and input queue must all 
be consistent, both internally and with respect to each other, before this 
command is used. 


This command does not start up the other TP processes. This command must 
be issued before other processes issue the tp worker start or tp_io_ start 
commands. 
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tp_stop tp_stop 


Name: tp stop 


The tp stop command shuts down transaction processing. First the I/O 
processes are told to stop accepting input. Then the worker processes are told 
to log out either when they have finished their current transactions, or when 
they have run out of work. Finally, the I/O processes log out after all output 
has been printed. 


When the I/O processes stop accepting input, a message is printed on all 
terminals that the TP subsystem is shutting down. All further input is ignored. 
The tp stop command does not wait for the worker or I/O processes to finish, but 
returns to command level. After the last I/O process has logged out, a message 
is printed on the master process's terminal indicating that TP shutdown is 
complete. 


Usage 
tp_stop {-control arg} 


where control arg may be -immediate or -im to specify that the worker processes 
should log out after finishing their current transactions. The default is for 
the worker processes to log out when the input queue is empty. 
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tp_who tp_who 


Name: tp who 


The tp_who command prints the names of the current users of a TP subsystem. 


Usage 
tp_who {TP_user_ids} {-control_args} 


where: 


1. TP_user ids 
‘are the TP_user_ids of TP users. 


2. control args 
may be chosen from the following list: 


-long, -lg 
prints the channel name and information about a user's terminal as 
well as the TP_user_id and I/O process name. The default is just to 
print the TP_user_id and I/O process name. 


-io_ process STR 


prints information only about users connected to I/0 process STR. 
STR is the I/O process name as used within the TP subsystem. 
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WORKER PROCESS COMMANDS AND SUBROUTINES 


This subsection contains descriptions of commands and subroutines that may 
be invoked in a worker process. The commands are used in the worker process 
absentee control segment and the subroutines may be used by TPRs. The worker 
process commands and subroutines are presented in alphabetical order within this 
subsection and include the following: 


tp rollback transaction 
tp verify transaction 
tp_worker init tef ~ 
tp_worker_ start 
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tp rollback transaction_ tp_rollback transaction _ 


Name: tp rollback transaction _ 


The tp rollback transaction Subroutine is called by a TPR to abort a 
transaction and roll back all changes made during the transaction. It should be 
called if a commitment would fail. This can be determined by calling either 
transaction call $status with the verify refs switch on or 
tp verify transaction . The TPR is automatically Yreinvoked if the TPR's retry 
limit has not been exceeded. This subroutine returns only if there is no 
transaction in progress. See the appropriate TPR language section in Section 6 
for information about closing files and other tasks that may have to be done 
before this subroutine is called. 


Usage 


declare tp_rollback transaction_ entry (); 


call tp_rollback transaction ; 
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tp_verify transaction _ tp_verify transaction_ 


Name: tp verify transaction_ 


The tp verify transaction subroutine may be called by a TPR to check if a 
commitment would succeed. A commitment may fail because of an asynchronous 
change made by another transaction. If an asynchronous change is detected, the 
TPR should call tp rollback transaction . Calling this subroutine has the same 
effect as calling Transaction call $status with the verify refs switch on. It 
is not necessary for TPRs to call this subroutine. It may be called between 
phases of a TPR to see if further processing would be worthwhile. A zero status 
code from tp_verify_transaction_ does not guarantee that a commitment would 
succeed. 


Usage 


declare tp verify _transaction_ entry (fixed bin(35)); 


call tp_verify_transaction_ (code); 


where: 


1 code (Output) 
is a standard status code. It may be: 
error table $asynch change 
if an asynchronous change was detected 
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tp_worker_ init tef tp_worker init tcf 


Name: tp worker init tcf 


Tne tp worker init tef command attaches and opens the TP subsystem's 
transaction control file (TCF) on the tcf I/O switch. This command must be 
invoked in a worker process before tp_worker_ start and before any databases are 
opened because the TCF I/0 switch, tcf , must be specified in the attach 
description of any file that is to be protected by the commitment mechanism. 


bh 
fl 


Usage 
tp_worker_init_tef path 


where path is the pathname of the directory containing the control segments for 
the TP subsystem. 


3-15 CC96 


tp_worker_ start tp_worker start 


ae. 


Name: tp worker start 


The tp_worker start command turns a_ process into a TP worker process and 
then starts processing transactions. This command must be invoked after 
tp_worker init tcf. 


Usage 


tp_worker_ start worker process name path 


where: 
ks worker process name 

is the name of the worker process as used within the TP subsystem. 
2 path 


is the pathname of the directory containing the control segments for 
the TP subsystem. 
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I/O PROCESS COMMANDS 


This subsection contains descriptions of commands that may be invoked in an 
I/O process. All of these commands except tp io start are TP user commands and 
must be entered in the command table as immediaté commands. Links to them must 
be placed in the commands directory. They should be invoked with the 
tp call strings af cali convention. The names used by TP users may be chosen 
by the TP administrator. 


The I/O process commands are presented in alphabetical order within this 
subsection and include the following: 


tp. 10.cancel 

tp io enter test mode 

tp io exit Test mode 

tp io get xen status 

tp io list pending requests 
tp io signoff a 

tp io start 

tp_io who 


Access to the TP Subsystem 


This section describes how a TP user’ starts a transaction processing 
session. The user must first connect a terminal to the I/0 process. This is 
done by using a terminal connected to a slave channel, or by using the dial 
access request. The signon TP access request is then used to start a 
transaction processing session. 


Name: signon 


The signon TP access request is used to gain access to the TP subsystem. 
It is a request to the I/O process to start the user identification and 
transaction processing procedures. 


The signon request asks for a password from the user, and attempts to 
ensure that the password does not appear at all on the user's terminal or that 
it is thoroughly hidden ina string of cover-up characters. The password is a 
string of one to eight letters and/or digits associated with a TP_user_id. 


After the user responds with a password, the I/O process looks up the 
TP_user_id and the password in the TP person-name table and verifies that the 
given password matches the password registered for the user. 


If the TP user is permitted to sign on, a transaction processing session is 
started, and the user may enter transactions. 
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Usage 


Signon TP_user_id 


where TP_user_id is the TP user's registered personal identifier. 
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tp_io_cancel tp_io_ cancel 


Name: tp _ io cancel 


Tne tp io cancel command removes one or more transactions from the input 
queue to prevent them from being processed. The transaction must not have 
started executing. Only the user's own transactions may be canceled. 


Usage 
tp_io_ cancel transaction _nums 


where transaction nums are the transaction numbers of the transactions to be 
canceled. 
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tp_io_enter_test_mode tp_io_enter_test_mode 


Name: tp _io_enter_test_mode 


The tp io enter test mode command causes the TP subsystem to execute and 
then automatically roll back all transactions entered by the user until the 
tp io exit test mode command is- given. THis does not affect the output 
generated by the transaction. 


Usage 


tp_io_enter_test_mode 
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tp_io_exit_test_mode tp_io_ exit _test_ mode 


Name: tp _io exit test mode 


Ti. 


The tp io exit test_mode command removes a user from test mode. All 
subsequent transactions are processed normally (committed instead of being 
rolled back). 


Usage 


tp_io_ exit _test_mode 
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—— 


tp_io get xen status tp_io_ get_xcn_ status 


— 


Name: tp_io_get_xcn_status 


The tp io get xen status command returns information about one or’ more 
transactions submitted by the user. If a transaction has not yet been 
processed, the TP command name, its deadline, its position in the queue, and the 
time it was submitted will be printed. If a transaction is currently being 
processed, the above information and the time it was started are printed. If a 
transaction has finished, except possibly for output, all the above information, 
the time it finished, whether there were any errors, real and cpu time used, 
page faults, and total real time, not including output processing, are printed. 


Usage 


tp_io_ get xcn_ status transaction _nums {-control arg} 


where: 
1. transaction_nums 

are the transaction numbers of the desired transactions. 
2s control arg 


may be -brief or -bf to print only the state of the transaction. 
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tp_io_ list pending requests tp_io list pending requests 


Name: tp_io list_pending requests 


The tp 


io list pending requests command lists the transactions submitted by 


the user that have not been completed. 


Usage 


tp_io_list_pending requests {-control_ args} 


where control args may be chosen from the following list: 


-total, 


-long, 


Bye 
prints only the total number of pending transactions for the TP 
subsystem and for the user. 


-lg 

prints the transaction number, deadline, and time submitted and the 
position in the queue of each pending transaction. The default is 
to print the transaction number and the position in the queue. 


-before DT, -be DT 


-after 


prints information about transactions with deadlines before the 
specified time. The DT argument is a string acceptable to the 
convert date_to_binary subroutine described in the MPM Subroutines. 


DT, -af DT 
prints information about transactions with deadlines after the 
specified time. Tne DT argument is a string acceptable ts the 


convert date to binary subroutine described in the MPM Subroutines. 
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tp_io_ signoff tp_io_signoff 


Name: tp _io signoff 


The tp io signoff command terminates a TP user's transaction processing 
session. 


Usage 
tp_io_signoff {-control arg} 


where control_arg may be -hold or -hd to retain communication with the TP 
subsystem. Another TP user may then immediately sign on. The default is to end 
communication with the TP subsystem. 
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tp_io start tp_io_start 


Name: tp io start 


The tp_io_start command turns a process into a TP I/O process. It attaches 
any specified channels and sets itself up as a dial server. 


Usage 


tp_io_start io_process_ name path {channels} {-control_ args} 


where: 
ee io_process name 
is the name of the I/O process as used within the TP subsystem. 
2 path 
is the pathname of the directory containing the control segments for 
the TP subsystem. 
Be channels 
are the names of slave channels. The channel names must be of the 
slave service type in the system channel definition table. 
4, control args 
may be chosen from the following list: 
-dial dial id 
establishes a dial line for dial id. This allows terminals to be 
connected to the I/O process via the dial access request. 
-registered dial dial id 
similar to -dial but allows users to omit specifying the User_id of 
the I/O process when invoking the dial access request. 
-Sswitch terminal to tp 
switches the handling of terminal I/O from Multics command level to 
the TP subsystem. This may be used for debugging. In an absentee 
process, the tp input I/O switch is opened for stream_input. Lines 
read from this I/O switch are interpreted by the TP subsystem. The 
tp_input 1/0 switch must already be attached. This allows prepared 
scripts of a TP session to be run. 
Notes 


The -dial and -registered dial control arguments are incompatible. Only 
one -dial or -registered dial control argument may be given. 


If a slave channel or -registered dial is being used, the I/O process must 


have access to the appropriate ACS. See the 
Multics Administrator's Manual -- System Administrator, Order No. AK50, for more 


information about access control segments. 
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tp_io_ who tp_io_who 


Name: tp _io_who 


The tp_io_ who I/O process command has the same function as the tp who 
master process command. See the description of the tp_who command in the master 
process command subsection. 
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COMMANDS USED OUTSIDE THE TP SUBSYSTEM 


This subsection contains descriptions of commands that are used outside the 


TP subsystem or in the master process. The TP administrator is the typical user 
of the commands in this subsection. The commands are presented in alphabetical 


order within this subsection and include the following: 


tp evset 

tp display command table 
tp display input queue 
tp display master table 
tp display output queue 
tp meters = 

tp pre create.ec 

tp reset xen num 

tp shrink q — 

tp user — 
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tp_cvsct tp_evset 


Name: tp_cvsct 


The tp_evset command is the TP source command table compiler. It converts 
a source language command table to the binary form usable by the TP subsystem. 


Usage 
tp_evsct path 


where: 


bs path 
is the pathname of the source command table. The source command 
table must have the tpsct suffix. This suffix is assumed if not 
given. 


Notes 


The binary command table is created in the working directory. Its 
entryname is that of the source segment with the tpbect suffix. It can be 
installed as tp_command_ table in the TP directory only when the TP subsystem is 
not running. = 


Description of the Command Table Source Language 


The source language for the command table consists of a list of statements. 
There may be a global section specifying default values that differ from the 
system-provided defaults, and then a section for each command. 

The syntax of a statement is: 
<keyword>: <parameter>; 


Comments are started with "/*" and ended with we sv, 


GLOBAL SECTION 


The global section consists of statements whose values are to be applied 
to all commands as default values. It appears at the beginning of the command 
table source segment and is terminated by the first name statement. 


The statements in the global section may be any of the statements described 
in the command section with the exception of the name and entry point name 
statements. The values specified in the global section may be overridden by 
statements in the command section. 
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tp_evsct tp_evsct 


The global section may specify a default call convention for only queued 
commands or immediate commands. If an immediate statement is present in the 
global section, this specifies to which type of command a giobali section cali 
convention statement applies. If an immediate statement is not present in the 
global section, a global section call convention statement applies to queued 
commands. 


COMMAND SECTION 


There must be a section in the source command table for each command 
available to the TP users. Each command section begins with a name statement 
and must also contain an entry point name statement. The other statements are 
optional. = = 


The statements are as follows: 


name: nameil, name2, ... namen; 
The parameter namei 1s a name by which a TP user can invoke the 
command. 


entry point name: STR; 
~ STR is the entry point name of the command. It may be of the form 
entryname or entryname$entry point name. All commands or links to 
them must be in a directory named “"commands" in the TP subsystem's 
directory. 


call _ convention: STR; 
STR is the entry point name of a subroutine that is used to invoke 
the command. It converts the input line into arguments for the TPR. 
It may be of the form reference name or 
reference namegentry point name. The search rules are used to find 
reference name. The default is the tp call strings subroutine for 
queued commands and the tp call strings af ‘Subroutine for immediate 


commands. See the "Standard Call Conventions" section below. 


cpu time limit: N; 

_ The parameter is a decimal integer specifying the maximum amount of 
cpu time, in seconds, that the command is to use on a single 
transaction. If the time limit expires, the transaction is aborted. 
The default is zero (no time limit). 


deadline interval: N; 

The parameter is a decimal integer specifying the offset in seconds 
from the time a transaction was queued to its deadline. Of two 
transactions in the queue at the same time, the one with the earlier 
deadline will be started first. No attempt is made to execute a 
transaction by the time indicated as its deadline. The deadline is 
only used to order the execution of transactions. The default is 
60. It may be negative. 


immediate: SIR; 
If STR is "yes", the command is executed in the I/O process. If STR 
is "no", the command is queued aS a_ transaction. This is the 


default. 
real time,limit: N; 
The parameter is a decimal integer specifying the maximum amount of 
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tp_evset tp_ecvsct 


real time, in seconds, that the command is to use on a_e single 
invocation. If the time limit expires, the transaction is aborted. 
The default is zero (no time limit). 


retry limit: N; 
~ The parameter is a decimal integer specifying the maximum number of 
times a transaction is to be re-executed if commitment fails. After 
N+1 tries, the transaction is aborted. The default is 3. 


Standard Call Conventions 


The following call convention Subroutines are supplied with the TP 
subsystem software: 


tp call strings processes the input line and invokes the command like 
re = ~ the Multics command processor. Each argument, as 
separated by white space, is passed as a character 
String. No active function, quoting or iteration set 

processing is done. 


tp_call string af Similar to tp cali strings except tne cofiand is 
called as an active function. 


Modifying the Source Command Table Compiler 


This section describes the steps necessary to add new items to the command 
table. 


es Add the new items to tp command table.incl.pll. 

2. Change the source command table compiler. See the description of 
reduction compiler in Multics System Programming Tools, Order 
No. AZ03. 

Dir Recompiie ail TP subsystem programs that use 
tp command table.inel.pl1, making appropriate changes to use the new 
items. = 
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tp_display_ command table tp_display command table 


Name: tp display command table, tpdet 


The tp_ display command table command prints the internal representation of 
a TP binary command table in put data format. The user should be familiar with 
the internal representation of a TP binary command table. . 


Usage 
tp display _command_table {path} 


where path is the pathname of a binary command table. The default is 
tp_command_table_ in the working directory. 
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tp_display input queue — tp_display input queue 


Name: tp display input _queue, tpdiq 


The tp display input queue command prints the internal representation of a 
TP input queue in put data format. The user. should be familiar with the 
internal structure of a TP input queue. 


Usage 
tp display input_queue {path} 


where path is the pathname of a TP input queue. The tpinq suffix is assumed if 
not given. The default is tp.tping in the working directory. 
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tp_display_master_table tp_display master table 


Name: tp display master table, tpdmt 


a ae ne 3 


The tp display master table command prints the contents of a TP master 
table in put data format. The user’ should be familiar with the internal 
representation of a TP master table. 


Usage 
tp display _master_table {path} 


where path is the pathname of a TP master table. The default is 
tp_master_table_ in the working directory. 


32°33 CC96 


tp_display output queue tp_display output queue 


Name: tp display output queue, tpdoq 


The tp display output queue command prints the internal representation of a 
TP output queue in put data format. The user should be familiar with the 
internal structure of a TP output queue. 


Usage 
tp_display output queue {path} 


where path is the pathname of a TP output queue. The tpoutq suffix is assumed 
if not given. The default is tp.tpoutq in the working directory. 
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tp_meters tp meters 


Name: tp meters 


Tne tp meters command displays metering information derived 
queue. This includes: 
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® the total cpu time and page faults for TPR execution 

® the number of successful completions 

8 the number of errors 

* the number of commitment failures 

% the minimum, maximum, average and standard deviation of the number of 
submissions per hour both total and per I/0 process’ (hours are 
measured from beginning of time period) 

& the minimum, maximum, average and standard deviation of the time 
between submission and processing 

e the minimum, maximum, average and standard deviation of the time spent 
in execution, both total and per worker 

Usage 


tp_meters path {-control args} 


where: 

Ae path 
is the pathname of a TP input queue to be metered. The suffix tping 
is assumed if not given. 

2s control args 


may be chosen from the following: 


-from DT, -fm DT 
specifies the beginning of the time period. DT must be a string 
that is acceptable to the convert date to binary subroutine 
described in the MPM Subroutines. The default is the earliest 
submission time of a transaction in the queue. 


-to DT 
specifies the end of the time period. DT must be a string that is 
acceptable to the convert date to binary subroutine described in 
the MPM Subroutines. The default is the current time. 
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tp_pre_create.ec tp_pre_ 


Name: tp pre create.ec 


The tp pre create exec com creates an empty indexed multisegment 
should be used before the first reference to an indexed file if the 
not exist or has been truncated. In particular, this should be used 
the TCF, the TP input queue and the TP output queue. 


Usage 
ec >unb>tp_pre create path 


where path is the pathname of the file to be created. 
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tp_ reset xcn num tp_ reset xcen_num 


Name: tp reset xcen_num 


The tp reset xen num command changes the TP subsystem's current transaction 
number to a specified value. The next transaction's transaction number will be 
the current transaetion number plus one. The current transaction number can be 
decreased only when the input queue is completely empty. See the tp shrink q 
command. This command should not be used when the TP subsystem is running. = 


Usage 


tp_reset_xcn_num path {transaction_num} 


where: 

1. path 
is the pathname of the directory containing the control segments for 
the TP subsystem. 

oa transaction num 


is the new current transaction number for the TP subsystem. The 
default is zero. 
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tp_shrink q tp_shrink_q 


Name: tp shrink _q 


The tp shrink _q command removes from a TP input queue records concerning 
transactions that were processed before a specified time. The records may be 
copied before they are deleted. 


Usage 


tp_shrink_q path {-control args} 


where: 

ihe path 
is the pathname of a TP input queue from which records are to be 
removed. The suffix tping is assumed if not given. 

Ze control _ args 


may be chosen from the following list: 


-before DT, -be DT 
removes records of only those transactions that completed before 
time DT. DT must be a String that is acceptable to the 
convert date to binary subroutine described in the MPM Subroutines. 
The default is the current time. 


-delete, -dl 
deletes records without copying them. 


-output description STR, -ods STR 
specifies that the records are to be copied before they are deleted. 
STR is the attach description of the file to copy the records to. 
It must be enclosed in quotes. 


-all, -a 
removes all eligible records. This is the default. 


-successful 
removes the records of transactions that completed successfully. 


-errors 
removes the records of transactions that aborted. These are 
transactions that failed for any reason except exceeding their retry 
limit. 


-commitment failure 
removes the records of transactions that could not be committed. 
These transactions exceeded their retry limits. 
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tp_shrink_q tp_shrink q 


Notes 
The -delete and -output description control arguments are incompatible. 


The -output description control argument may be used to specify a file in 
the storage system or a tape by using appropriate attach descriptions. 


This command can be executed while the TP subsystem is running. It can 
also be uSed in several processes simultaneously to do such things as put 
records of successful transactions on tape and records of commitment failure 
transactions into a file. ; 
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tp_user tp_user 


Name: tp_user 


The tp user command edits the TP person-name table. It registers TP users, 
deregisters TP users and changes their passwords. This command should not be 
used while the TP subsystem is running. A TP user should not be deregistered if 
he is signed on, has pending transactions in the input queue or has pending 
output in the output queue. 


Usage 


tp_user {path} {-control arg} 


where: 

Te path 
is the pathname of the TP subsystem's person-name table. The 
default is tp _person_name table in the working directory. 

eae control arg 


may be tne following: 


-input file path, -if path 
specifies that the input is to come from the segment whose pathname 
is path. The segment contains exactly the same input as the user 
would type if the command were being used interactively. If there 
are any errors, write requests will not be performed and the user 
will be questioned at the end. 


The tp_user command keeps prompting the user for requests until the user is 
finished. Requests that change the information in the TP person-name table are 
called action requests. The action requests are the following: 


add_user, au register a new TP user 

delete user dlu deregister a TP user 

change password, cpw change a TP user's password 

verify password, VpW verify what a TP user's password is 


Typing a TP user id after an action request performs that action for a TP 
user. As many TP user ids may be typed after an action request as desired. The 
last action will be performed on succeeding TP user ids until another action 
request is typed. The prompt indicates what the last action request was. Each 
action request is explained in more detail below. 


TP_user_ids may contain uppercase characters, lowercase characters, numbers 
or underscores. They must begin with an uppercase character. TP_user_ids are 
from one to 32 characters’ long. TP_user_ids are not related to Multics 
User ids. 


Passwords may contain letters or digits. They are from one to eight 
characters long. If a password is not typed ahead, the user will be prompted 
for it. The tp_user command attempts to ensure that the password does not 
appear at all on the user's terminal or that it is thoroughly hidden in a string 
of cover-up characters. 
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tp_user 


As much input may be typed ahead on a single 
password ahead, enclose it in braces, e.g. {passw 
ahead, it will not be hidden. 


The action requests do the following: 


add_user, au 


registers a TP user. 


delete user, dlu 


“deregisters a TP user. 


change password, cpw 
changes a TP 
entered next. 


verify password, vpw 


verifies a TP user's 
informed if the 


user is 
user. 


In addition to the above action requests, 


also available: 


previous, p 
whenever a TP 


user's password. 


password. 
typed 


user id is typed, 


ine a 


The TP user's password 


The new password 


A password 
password is the 


it is 


tp_user 


s desired. To type a 
} If a password is typed 


is entered next. 


of the TP user is 


is entered next and the 
password of the TP 


the following requests are 


remembered. The previous 


request uses the last TP_user_id with the current action request. 


write, w 
writes all changes into the TP person-n 
change a copy of the TP person-name t 
permanent until a write request is done. 
quit, q 
exits the tp user command. If the TP 


€ e 
ble. Ch 


Action requests 
nges are not made 
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person-name table has been 


changed since the last write, the user is questioned. 


help 


prints information about what may be typed next. 


prints a list of requests 


Example 


The following example 


changes the password of MJones. 


line is typed by the user. 


! tp user 


registers WSmith, CKent, 


Type "help" for instructions. 


Request: ! 


au WSmith CKent 


Password for WSmith: 
Password for WSmith again: 
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and RDavis as TP users and 


Everything following an exclamation point on a 
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tp_user 


Password for CKent: 
Password for CKent again: 


Add user: ! RDavis 


Password for RDavis: 
Password for RDavis again: 


Add user: ! cpw MJones 


New password for MJones: 
New password for MJones again: 


Change password: ! write quit 
r 1402 0,600 2.2330 102 


tp_user 
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This section contains descriptions of the transaction_call command and the 
transaction call subroutine. They are included in this manual because their 
interfaces are still preliminary. The transaction call_ subroutine is used by 
the TP monitor and should not’ generally be used by TPRs. The commands and 
Subroutines described in this section are independent of the TP subsystem 
described in the rest of this manual. The commands and subroutines described in 
this section may be used without the TP subsystem. 


Note that "transaction" has a different meaning in this section than in the 
rest of the manual. A vfile transaction is a unit of processing that has the 
appearance of taking place as an indivisible, atomic operation. The transaction 
numbers used by vfile bear no relation to the transaction numbers seen by the 
users of a TP subsystem. 


Transactions 


A transaction is a unit of processing that has the appearance of taking 
place as an indivisible, atomic operation. Arbitrary procedures involving any 
collection of vfile indexed files may be invoked as transactions via this 
subroutine. a 


APPEARANCE 


An incomplete transaction terminates either by a successful commitment or 
by a rollback. That is to say, until a commitment is made, the database appears 
unchanged, except within the current transaction. Any database modifications 
that a transaction makes appear simultaneously outside the transaction when a 
commitment is made. 


PURPOSE 


The first is to simplify the programmer's task of handling inconsistencies that 
can arise from operations that are interrupted and not resumed. This may be 
because of a system crash or an application program error. Second, in the event 
that a database is shared among several processes, the entire burden of 
synchronizing file access is removed from the programmer and automatically 
managed by transaction call . 
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TCF I/O SWITCH 


Fach process’ that uses transaction call_ requires an I/0 switch that 
associates transactions with a particular database. This I/O switch is attached 
by the user to a permanent transaction control file (TCF). This is used in 


conjunction with the files that compose a single logical database. 


TRANSACTION NUMBERS 


Each transaction associated with a TCF has a transaction number. 
Associated with each TCF I/O switch is a current transaction number. Initially 
and after a commitment or rollback, the current transaction number is zero 
indicating that no current transaction is defined for a TCF I/0 switch. A 
transaction number is assigned automatically when an indexed file attached with 
the -transaction option of vfile is referenced and the current transaction 
number is zero. ~ 


REFERENCE LISTS 


A per-process reference list is automatically maintained with each TCF I/0 
Switch. It is implemented as an indexed file without records. The reference 
list keeps track of passive references made during the course of each 
transaction so asynchronous changes that might invalidate a transaction can be 
detected. The reference list also identifies all items modified during the 
transaction in order to make the database consistent at commitment or rollback 
time. 


Files 


DATABASE 


Any collection of vfile indexed files may be a database upon which 
transactions are applied. AlI that is required is that a common TCF always be 
used in conjunction with references to any file in the database, and that the 
individual database files be attached with the -transaction option of vfile 
specifying a TCF I/O switch attached to the TCF of the database. = 


TRANSACTION CONTROL FILE 


The TCF is a permanent indexed file containing index entries but no 
records. The user is responsible for its creation, but the TCF is implicitly 
manipulated by vfile and transaction call , so that no explicit user operations 
on the TCF are required. ~ ~ 


TCF ENTRIES 


Keys are added to the TCF when a transaction number is assigned for a new 
transaction. Each key's descriptor is a flag indicating the logical completion 
state of a single transaction. Thus the atomicity of a transaction is reduced 
to changing the descriptor of its TCF entry. 


4-2 CC96 


OPENING CONSTRAINTS 


In order to use transaction call , the user must first attach and open the 
database's TCF. Then all database files to be referenced must be attached and 
opened before starting any transactions. None of these files should be closed 
within a transaction. If coneurrent transactions are performed on a common 
database, the -share option of vfile must be given in the TCF attach 
description as well as in the attach descriptions of the shared database files. 


ASYNCHRONOUS CHANGES 


When a commitment is attempted or upon referencing a database item 
previously read in the same transaction, it is possible that an error resulting 
from an asynchronous change by another transaction may be detected. An 
asynchronous change occurs when the current transaction reads an item, and then 
another transaction makes a commitment which changes the item before the current 
transaction commits or rolls back. This situation makes it impossible to 
correctly complete the current transaction, and the transaction must be rolled 
back. To determine whether an unexpected error was caused by an asynchronous 
database change, use the transaction call $status entry with the verify refs 
switch on. 7 = . 


See the description of the vfile I/O module in the MPM Subroutines. See 
the description of the transaction call command for a description of the command 
level interfaces corresponding to The transaction call_ entries. 
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transaction call transaction call 


Name: transaction call, tre 


The transaction call command performs, controls, or obtains’ status 
information about atomic database operations. 


Usage 


transaction call opname switchname {args} 


where: 
Ihe opname 
designates the operation to be performed. 
an switchname 
is the name of the transaction control file (TCF) I/O switch. 
3% args 


are variable, depending on the particular operation to be performed. 
The opnames permitted, followed by their alternate forms, are: 
assign, a 
commit, c 
number, n 
rollback, r 


Status, s 
transact, t 


Usage is explained below under a separate heading for each designated 
operation. The explanations are arranged alphabetically rather than 
functionally. 


Operation: assign, a 
transaction call assign switchname 


This command reserves a unique’ transaction number for the current 
transaction by creating a new entry in the TCF. 


Operation: commit, c 


transaction call commit switchname 


This command attempts to complete the current transaction. If successful, 
the current transaction number is reset to zero. 
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transaction call transaction call 


Operation: number, n 


transaction call number switchname 

This command prints the current transaction number. 
Operation: rollback, r 

transaction call rollback switchname 


This command undoes all modifications made on behalf of the current 
transaction and resets the current transaction number to zero. 


Operation: status, s 


transaction call status switchname {transaction_ no} {-control_ args} 


where: 

he transaction no 
is the number of the transaction whose status is to be found. If 
omitted or zero, the current transaction number is used. 

2% control args 


may be chosen from the following: 

-brief, -bf 
suppresses the counting and printing of the number of passive and 
nonpassive references made by the transaction. 

-verify, -vf 


specifies that all passive references are checked for asynchronous 
changes. 


This command prints the status of any transaction associated with a TCF. 
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transaction call transaction call 


Operation: transact, t 


transaction call transact switchname {-control args} command line 


where: 
Ale control args 
may be chosen from the following: 
-retry N 
specifies the maximum number of times the transaction is to be 
retried if commitment fails. The default is zero. 
-signal 
specifies that if commitment fails and the retry count has been 
exceeded, the transaction failure condition is signaled. This is 
the default. 
-no_signal 
specifies that’ the transaction failure condition should not be 
Signaled if commitment fails and the retry count has been exceeded. 
eae command line 


is a Multics command line that need not be enclosed in quotes. 
This command executes a given command line as a transaction. 


If the -signal control argument is specified, a handler for the 
program interrupt condition is established. This handler re-executes’ the 
command line. The default action for the transaction failure condition prints a 
message and returns to command level. The start command does not re-execute the 
command line. The transaction is rolled back before the transaction failure 
condition is signaled. = 


Notes 


If no transaction number has’ been obtained via the assign operation, a 
transaction number is automatically assigned upon the first reference toa 
database item within a new transaction. The TCF I/0 switch must be open for 
update. 


See the description of the transaction_call_ subroutine for more detailed 
information. 
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transaction call _ transaction call 


Name transaction call 
The transaction call subroutine manages the transaction mechanism of 
vfile , including committing and rolling back. 


Entry: transaction call $assign 


This entry reserves and returns a unique transaction number for the current 
transaction. The current transaction number must be zero, i.e., undefined, 
before this entry is used. The current transaction number is changed to the 
transaction number of the transaction. The TCF I/0 switch must be opened for 
update so that a new entry can be created. 


Usage 


declare transaction call $assign entry (ptr, fixed bin(35), fixed bin(35)); 


call transaction call $assign (tef_iocb ptr, transaction no, code); 


where: 
1. tef_iocb_ptr (Input) 
is a pointer to the iocb for the TCF I/O switch. 
2. transaction no (Output) 
is the new transaction number. 
3. code (Output) 
is a standard status code. 
Notes 


The user is not’ required to assign a transaction number at all, in which 
case one iS automatically assigned upon making the first reference to a database 
item of the new transaction. 


Entry: transaction call $commit 


This entry attempts to complete the current transaction on a_ database 
associated with a TCF I/O switch. The current transaction number becomes zero 
if the commitment is successful. 


ic. CC96 


ee 


transaction call _ transaction call _ 


ee re ee ne nr i ee 


Usage 


declare transaction call $commit entry (ptr, fixed bin(35), fixed bin(35)); 


call transaction call $commit (tcf_iocb ptr, transaction no, code); 


where: 
Ts tef_iocb ptr (Input) 

is a pointer to the iocb for the TCF I/0 switch. 
2 transaction no (Output) 

is the transaction number of the transaction whose completion was 

attempted. 
3. code (Output) 

is a standard status code. It may be: 

error _table_ $asynch_ change 

if an asynchronous change was detected 

Entry: transaction call $number 


This entry returns the current transaction number. 


Usage 


declare transaction call $number entry (ptr, fixed binary (35), fixed 
binary (35)); 


call transaction_call_ $number (tcf_iocb ptr, transaction _no, code); 


where: 
qs, tef_iocb ptr (Input) 
is a pointer to the iocb for the TCF I/O switch. 
2. transaction _no (Output) 
is the current transaction number. 
2 code (Output) 
is a standard status code. 
Entry: transaction call $rollback 


This entry undoes all modifications that have been made by the current 
transaction in a database. 
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transaction call_ transaction call _ 


Usage 


deciare transaction cali $rolliback entry (ptr, fixed bin(35), fixed 
bin(35))35 - . 


call transaction call $rollback (tef_iocb ptr, transaction no, code); 


where: 
Ts tef_iocb ptr (Input) 
is a pointer to the iocb for the TCF I/O switch. 
2% transaction_no (Output) 
is set to the transaction number of the aborted transaction. 
3. code (Output) 
is a standard status code. 
Notes 


The effect of a rollback is logically invisible outside the current 
transaction. The transaction number for a rolled-back transaction is not 
reused. After issuing a rollback, the current transaction number of the TCF I/0 
Switch becomes zero, i.e., undefined, and the database is restored to the state 
following the last commitment. 


Entry: transaction call $status 


This entry returns the status of any transaction associated with a TCF. If 
the verify refs switch is on, this entry checks items in the reference list of 
the transaction for asynchronous changes caused by another transaction. 


Usage 


declare transaction call $status entry (ptr, fixed binary (35), bit (36) 
aligned, ptr, fixed binary, fixed binary (35)); 


call transaction call $status (tcef_iocb ptr, transaction no, tre flags, 
tre _ status ptr, transaction status, code); 


where: 
ic. tef_iocb ptr (Input) 

is a pointer to the ioecb for the TCF I/O switch. 
2. transaction no (Input) 


is the transaction whose status is desired. Zero indicates the 
current transaction. 
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transaction call _ transaction call_ 


3 tre flags (Input) 
indicates what operations to perform. See "Notes" below. 


4, tre status ptr (Input) 
~ is a pointer to a tre status structure in which information is 
returned. If this pointer is null, the information contained in the 
structure is not returned. See "Notes" below. 


Bs transaction status (Output) 
is the status of the transaction. See the description of 
transaction status in the tre status structure below. 


6. code (Output) 
is a standard status code. It may be: 


error_table $asynch_change 
if an asynchronous change was detected 


Notes 
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The tre flags argument is a bit string of the following structure: 


declare 1 tre flags s aligned based (addr (tre _flags)), 
2 verify refs bit(1) unaligned, 
2 pad bit(35) unaligned; 
where: 
1. verify refs (Input) 


indicates whether or not to check for asynchronous changes. 
"O"b don't check for asynchronous changes 
"1b check for asynchronous changes 


2. pad (Input) 
is reserved for future use and must be zero. 


This structure is declared in transaction call.incl.pli. 


The tre_status_ptr pointer points to the following structure: 


declare 1 tre status aligned based (tre status ptr), 

2 version fixed binary, 
2 transaction_no fixed binary (35), 
2 transaction status fixed binary, 
2 passive refs fixed binary (34), 
2 non_passive refs fixed binary (34); 

where: 

1% version (Input) 


is the version of the tre status structure. It must be 1. 
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transaction call_ transaction call _ 


tion no (Output) 
is the transaction number of the transaction the status information 
describes. 


a3 status (Output) 
is the status of the transaction. It may be: 
tre INCOMPLETE (0) The transaction is in progress but has not 
= been committed or rolled back yet. 
tre COMMITTED (1) The transaction has been committed. 
tre ROLLED BACk (2) The transaction has been rolled back. 
tre UNDEFINED (3) No TCF entry for this transaction exists. 


4, passive refs (Output) 
Is the number of items referenced but not modified in the 
transaction so far. 


5. non_ passive refs (Output) 
is the number of items modified in the transaction so far. 


The structure and the named constants are declared in the include 
file transaction call.inel.pli. 


Entry: transaction call $transact 


This entry executes a command line as an atomic transaction on a specified 
database. If the commitment is unsuccessful, the transaction is rolled back. 


Usage 
declare transaction call $transact entry (ptr, char(*), fixed bin (35), 
fixed bin (35)); 


call transaction call $transact (tef_iocb ptr, command line, 
transaction no, code); 


where: 
1% tef_ioecb_ptr (Input) 
is a pointer to the iocb for the TCF I/O switch. 
2. command line (Input) 
is a Muitics command line that is to be executed as a_ single 
transaction. 
3. transaction no (Output ) 
is the transaction number of the transaction. 
4, code (Out put) 


is a standard status code. It may be: 
error table $asynch change 
if the transaction was rolled back 
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SECTION 5 


ERROR HANDLING AND RECOVERY 


CRASH RECOVERY 


A system crash usually does not result in the loss of data. However, 
processes are destroyed and so transactions are interrupted. When transaction 
processing starts again, new processes are created. All work associated with 
incomplete transactions is discarded. The aborted transactions are 
automatically rescheduled. When there is loss of data, most of the input queue 
should be intact on disk. Records modified after the time corresponding to a 
consistent database should be made consistent with the rest of the database. 
Those transactions should then be rerun. 


No facilities are provided with this release for journalizing the input 
queue or for adjusting databases or queues in case of loss of data. 


TRANSACTION ERROR HANDLING 


The TP subsystem recovers from unexpected errors by TPRs. When a TPR 
raises an unrecoverable condition, the worker process aborts the transaction and 
sends the user a message to that effect. A message with the actual cause of the 
error is written into the absentee output segment. Then the worker process 
roiis back any changes made and goes on to the next transaction. Recoverable 
conditions include command error and endpage. A TP administrator can insert his 
own condition handler to detect what he considers to be recoverable conditions. 


Sometimes a transaction cannot be committed because of asynchronous changes 
caused by another transaction. When this happens, the changes made by the 
transaction are rolled back and the transaction is retried. The maximum number 
of retry attempts for a particular TPR is specified in the command table. 
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SECTION 6 


GUIDELINES FOR WRITING TPRS 


DESCRIPTION OF OPERATING ENVIRONMENT 


All TPRs run in the worker process, except for immediate commands which run 
in the I/O process. Therefore, Multics access control is performed with respect 
to the worker or I/O process's access identifier, not the TP user who submitted 
the transaction. A TPR should not alter the environment by changing such things 
as the working directory or search rules. TPRs must be serially reusable. 
Therefore, a TPR must explicitly initialize certain types of data rather than 
use language initialization facilities. See the appropriate language section 
below. TPRs may call other programs; however in the worker process, the other 
programs should be explicitly initiated in the worker absentee control segment. 
All TPRs in the worker process are run within a run unit. There is not 
necessarily a new run unit for each transaction. TPRs may not start new run 
units because run units’ are not recursive. TPRS may be installed whenever the 
TP subsystem is not running. 


CALLING CONVENTIONS 


TPRs are called using a call convention specified in the command table. A 
TP administrator may define TP subsystem specific call conventions. A call 
convention specifies the relation between the command line a TP user enters and 
how the arguments are passed to the TPR. The command table specifies. an 
external procedure which implements the call convention. 


IMMEDIATE COMMANDS 


Immediate commands are called as active functions. The active function 
return string is printed on the TP user's terminal. Immediate commands should 
not make database references or do any input/output with the terminal. 


INPUT/OUTPUT 


Input/Output in the TP subsystem may be of various kinds: 
& Terminal Input 
® Terminal Output 

File Input/Output 


e Peripheral Input/Output 
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Their relation to the TP subsystem is explained in the following paragraphs, as 
well as use of the Multics Relational Data Store (MRDS). 


Terminal Input 


In this release, TPRs may not ask for input from the TP user who submitted 
the transaction. All input from the user must be specified on the command line. 
TPRs should not try to read from the user_input I/O switch. 


Terminal Output 


In the worker process, the user_output I/0 switch is attached to an I/0 
module which puts output into the output queue. Therefore, anything written on 
the user output I/O switch is ultimately printed on the terminal of the TP user 
who submitted the transaction. A TPR may not send output to any other TP user. 
A TPR should not make any assumptions about the physical characteristics of a TP 
user's terminal. The terminal a TP user enters a transaction from may not be 
the same one that he is using when the output is printed. 


The error_output I/O switch is attached to the I/0 or worker process's 
absentee output segment. Therefore, error_output may be used to log errors or 
messages. 


File Input/Output 


All I/O switches used by any TPR should be attached and opened via io call 
in the worker process absentee control segment to reduce TPR execution overhead. 
Refer to the specific language section to determine when a file opened with 
language I/O facilities needs to be closed with language I/0 facilities. In the 
Multics I/O system, there is a distinction between directly invoking the I/0 
system to open or attach an I/0 switch and using language I/0 facilities to open 
a file. Language I/0 facilities will leave the I/0 switch in the state in which 
they found it. See the MPM Reference Guide, "Programming Language Input/Output 
Facilities", for more information. Only vfile indexed files may be protected 
by the commitment mechanism. ~ 


Sometimes an asynchronous change causes a language I/O error. The TPR must 
determine if language I/O errors are the result of an asynchronous change or 
something fatal. If the language I/O error was caused by an asynchronous 
change, the TPR should call tp rollback transaction . Each section on TPR 
languages explains how to handle this problem. = 


Peripheral Input/Output 


TPRS may request that files be printed with the dprint subroutine 
described in the MPM Subsystem Writer's Guide. Tapes may be used via the tape 
I/O modules described in the MPM Peripheral Input/Output manual. If a TPR 
attaches a tape, it should also detach it and establish a cleanup handler to 
detach the tape if the TPR is aborted. 
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Using MRDS 


All databases used by any TPR should be opened in tp init database.ec to 
reduce TPR execution overhead. All files of a database that will be used should 
also be readied in tp init database.ec. When a TPR is invoked, all its 
databases should be open and all files that will be used should be ready. A TPR 
may call dsl_$get_dbi to obtain the database index. TPRs should not finish a 


file or close any databases. When a database is created, the -control control 
argument of create _mrds db should be used to specify the TP subsystem's TCF. 


TPR LANGUAGES 


PLAL 


TPRs must initialize all static storage each time they are called. The 
stop statement should not be used. Output written on the default sysprint file 
is ultimately printed on the TP user's terminal. The default sysin file should 
not be read from. The columnposition, linenumber and pagenumber of external 
files are undefined when a TPR is started. 


Before a TPR returns and before tp rollback transaction is called, the TPR 
need only close stream files and record files for which locate statements are 
being used. The TPR should also free any based or controlled storage that is 
allocated. It is not necessary to have a cleanup handler that closes files or 
frees based and controlled storage. A cleanup handler is needed to detach a 
tape only if language I/0 facilities were not used to attach the tape. 


Oniy PL/I indexed sequential data sets may be protected by the commitment 
mechanism. An asynchronous change may cause the transmit condition to be 
raised. The following on unit should be included in each TPR to roll back the 
transaction if an asynchronous change occurs. It should be established for each 
file protected by the commitment mechanism. The identifier "keyed file" below 
is the file value for which on unit is established. 
on transmit (keyed file) 

begin; 

declare code fixed binary (35); 
declare continue _to signal entry (fixed binary (35)); 
declare transaction error condition; 
declare error _table_ _$asynch_ change 

fixed binary (35) external static; 
declare error table $asynch deletion 

fixed binary (35) external static; 
declare error table $asynch insertion 

fixed binary (35) external static; 
declare error table $record_ busy 

fixed binary (35) external static; 
declare pl1 io $error code entry (file) returns (fixed binary (35)); 
declare tp rollback transaction 

entry (); 
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code = pl1_io $error_code (keyed file); 
if code = error table $asynch change 
; code = error table $asynch deletion 
| code = error table $asynch insertion 
' code = error table $record busy 
then call tp rollback transaction ; 
call continue to signal (code); 
if code “= 07 ~— F 
then signal transaction error; 
end; - 


COBOL 


COBOL TPRs run in implicitly started COBOL run-units. Therefore the STOP 
or STOP RUN statements should not be used. The EXIT PROGRAM statement should be 
used to finish a TPR. Input from the command line can be passed as a character 
string or a structure to the COBOL TPR by a call convention routine written in 
PL/I. See the Multics COBOL Users' Guide, Order No. AS43, for more information. 
Since a program may be called many times within a COBOL run-unit, all data 
should be explicitly initialized when the TPR starts. The ACCEPT statement 
should not be used. The DISPLAY statement with the UPON SYSOUT phrase may be 
used to output information to the TP user who submitted the transaction. The 
DISPLAY statement with the UPON CONSOLE phrase may be used to put messages into 
the worker process! absentee output segment. The COBOL Message Control System 
should not be used. 


To réduceé overnead associated with opening and ciosing files, an external 
switch should be used to indicate if files have been opened. The first thing 
every COBOL TPR should do is call an initialization program to open files if the 
external switch is off. The called intialization program should open all 
external files that are used by any TPR. The initialization program should then 
turn the external switch on to indicate that files have been opened. It is not 
necessary to close external files. 


Only COBOL files with relative organization or indexed organization may be 
protected by the commitment mechanism. The FILE-CONTROL paragraph for each file 
protected by the commitment mechanism should include the following FILE STATUS 
clause: 


FILE STATUS IS status-key-name-1, status-key-name-2 
The status keys are described as follows: 


WORKING-STORAGE SECTION. 
01 status-keys. 
O02 status-key-name-1 PICTURE XxX. 
02 status-key-name-2 PICTURE 9999. 
02 status-key-3 REDEFINES status-key-name-e. 
03 w PICTURE 9. 
03 x PICTURE 9. 
03 yz PICTURE 99. 


6-4 CC96 


The following USE procedure should be included in each TPR to roll back the 
transaction if an asynchronous change occurs. It should be specified for each 
file protected by the commitment mechanism. The word "file-name" below is the 
file for which the USE procedure is specified. 


PROCEDURE DIVISION. 
DECLARATIVES. 
eneck-Status SECTION. 
USE AFTER STANDARD ERROR PROCEDURE ON file-name. 


check-for-asynch-change. 


IF (status- ~key-name-| = "30'") AND Cw = 3 OR 4 OR 5 OR 6 OR t2) 
AND (x = 4 OR 6 OR 7 OR 8) AND (yz = 30) 


CALL "tp rollback transaction_". 
CALL "print cobol error $switch" USING “error output". 
CALL "signal __ " USING "transaction_ error", 
EXIT PROGRAM. 
END DECLARATIVES. 


FORTRAN 


FORTRAN TPRs should be written as FORTRAN subroutines. The stop statement 
should not be used. The return statement should be used to finish a TPR. Input 
from the command line can be passed as arguments to the FORTRAN TPR by a call 
eonvention routine written in PL/I. Alternatively, the PL/I call convention 
routine can put the TPR's’9 input into a FORTRAN common block. See the 
Multics Fortran Users' Guide, Order No. CC70, for more information about how 
PL/I and FORTRAN programs Communicate. TPRs should not use the read statement 
with the default unit numbers (5 or 41) or the input statement. To produce 
output that is ultimately displayed on the terminal of the TP user who submitted 
the transaction, use the write statement with the default unit numbers (6 or 42) 
or the print statement. 


It is not necessary for FORTRAN TPRs to explicitly close files. However, a 
TPR should explicitly close a tape file when it is finished with it. 


OrCAn 


Only FORTRAN direct access files may be protected by the commitment 
mechanism. An asynchronous change may result in an error message in the 
absentee output segment. This message can be ignored. A FORTRAN TPR need not 
include error processing for asynchronous changes. If a FORTRAN TPR encounters 
an asynchronous change, the transaction will be rolled back and retried. 


COMMITMENT AND ROLLBACK FEATURES 


The system provides a commitment facility which updates a file with all 
changes made by the process since the last commitment. Any changes made before 
the commitment are invisible to other users. At any time before the commitment, 
all changes made since the last commitment may be rolled back. 


In the TP subsystem, a commitment is automatically attempted at the end of 
each transaction. It is recommended that TPRs not perform intermediate 
commitments since this may affect the TP recovery mechanism, 
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However, if a TPR takes a long time to execute, there is an increased 
probability that some of the records read would have since been changed by 
another transaction. If this is likely, the TPR should be written to include a 
call to transaction call $status with the verify refs switch on or to 
tp verify transaction . This will indicate whether a commitment would succeed 
if issued at that time. If it wouldn't, there is no reason to continue further. 
The TPR should call the tp rollback transaction subroutine which will roll back 
the current work and reinvoke the TPR. ia 
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aborting transactions 
see tp rollback transaction_ 
subroutine 


access 1-4, 2-3, 2-4, 6-1 
see access control list 
access control lists (ACLS) 2-2 


adding TP user 
tp_user command 


assign operation 
see transaction call command 


asynchronous changes 
4-10, 5-1, 6-2 


3-14, 4-3, 4-5, 


atomic database operations 4-4 
attaching slave channels 
see slave channels 


binary command table 
see tp_evsct command 
tp_display command table 


call convention 3-29, 6-1, 6-5 
canceling changes 

see tp rollback transaction_ 
subroutine 


canceling transactions 
see tp cancel command 
see tp io cancel command 


changing TP user password 
tp_user command 


changing transaction number 


3-37 


channels 2=+9, 3-11 
COBOL 
see TPR languages 


coliection deiay time 


command context 
I/O process 3-1 
master process 
outside TP 3-1 
worker process’ 


3-1 

3-1 
command directory 2-3, 2-6 
command line 


executed as a transaction 
executed as transaction 


4o11 
4-6 


command processing 3-30 


INDEX 


command table 2-6, 3-28, 6-1 
compiler modification 3-30 
see source language command table 


commands used outside TP 3-27 


commit operation 
see transaction call command 


commitment 2-4, 3-13, 3-14, 3-15, 
3-35, 3-39, 5-1, 6-5 


constraints 
see file opening constraints 


cpu time 
see tp_meters command 


creating an empty file 3-36 


deadline 1-1, 1-4, 3-5, 3-22, 3-29 
see tp_change deadline command 


deadline time 3-29 


debugging tools 


isplay master 
Splay output queue 


defining a TP subsystem 2-1 


deleting records from input queue 


deleting TP user 
tp_user command 

dial access request 2-9 

dial facility 1-4, 2-3, 2-9 


dialok 2-3 
see dial facility 


dial_id 2-1, 3-25 
see dial facility 


directory of commands 2-3 


ear 
see enter_abs_ request 


enter_abs request command 2-7 
error handling 5-1 


errors 
see tp meters command 
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file garbage collection 
collection delay time 


file input/output 6-1 
file opening constraints 4-3 


FORTRAN 
see TPR languages 


I/O process 1-2, 1-4, 2-2, 2-7, 2-9, 
3-1 
absin file 2-4 


I/O process commands 3-17 


immediate commands 1-4, 3-30, 6-1 
initiating transaction processing 
3-17 


input queue 1-2, 1-4, 2- 
3-4, 3-7, 3-19, 3-35 
maintenance 2-8 
removing records 
see tp_shrink_q command 
tp_display_input_queue 


1, 2-4, 2-8, 
, 3-36 


input/output 6-1 
file 6-1 
peripheral 6-1 
terminal 6-1 


io_start_up.absin 2-4 
see I/0 process 


language I/O facilities 6-2 


languages 1-1 
see TPR languages 


Managing transaction processing 2-7 


master process 1-2, 1-4, 2-2, 2-3, 
2-7, 2-8, 2-9, 3-1, 3-9 


master process commands 3-3 


master table 1-4, 2-3 
tp_ display master table 


metering information 3-7, 3-35 
MRDS 2-1, 2=4 


Multics Relational Data Store (MRDS) 


Multics TP subsystem 
see TP subsystem 


nonpassive references 4-5 


number operation 
see transaction call command 


operating a TP subsystem 2-7 
order of execution 1-6 


output queue 1-2, 1-4, 2-1, 2-4, 3-36 
tp_display output queue 


page faults 
see tp _ meters command 


parallel TP subsystems 2-9 
passive references 4-5 
pending requests 
see tp_io_list_pending requests 
command 
see tp_list_pending requests command 


peripheral input/output 6-1 


personal identifier 
see TP_user_id 


PL/I 
see TPR languages 


processing transactions 
see tp worker start command 


proxy 2-3, 2-6 


reference list 4-2 


registered personal identifier 
see TP_user_id 


removing records from input queue 


removing transactions 
see tp cancel command 
see tp_io_ cancel command 
restart 1-4, 2-7 


rollback 1-1, 1-4, 3-13, 3-20, 4-9, 
6-5 


rollback operation 
see transaction call command 


rolling back changes 
see tp roliback transaction _ 
subroutine 


run unit 2-4, 6-1 


security 1-4 
setting up a TP subsystem 2-3 


shutdown 1-4, 2-8 
see tp stop command 


shutting down transaction processing 
1-4 


Ssignon TP access request 3-17 
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slave channels 2-9, 3-25 


source language command table 
See tp_evsct command 


Starting a TP subsystem 
tp_ start command 


Starting transaction processing 2-7 


eommand 


tp start comm 


status of transactions 
see tp get_xen_status command 
see tp io get xcn status command 


status operation 
see transaction call command 


Subroutine context 
worker process 3-1 
successful completions 

see tp meters command 


System administrator 2-3 


system crash 4-1, 5-1 


TCF 
see transaction control file 


terminal input 6-1 
terminal output 1-4, 6-1 


terminating transaction processing 
see tp_io signoff command 


test mode 
see tp io enter_test_mode command 
see tp io exit_test_mode command 


test processes 2-9 
testing 2-9 
TP administrator 1-4, 2-2, 2-3, 
5-1, 6-1 
TP process names 2-2, 2-4 
“TP session 3-9 
TP subsystem 1-1, 1-2 


attaching TCF 
see tp worker init tef command 
call conventions 6-1 
command table 6-1 
commands 3-1 
commands used outside 3-27 
defining a subsystem 2-1 
deregister user 
tp_user command 
directory 2-3, 2-7 
error handling 5-1 
initiating a TP session 
see Signon TP access request 
input/output 6-1 
opening TCF 
see tp worker init_tcef command 
process names 2-2 
register user 
tp_user command 
see command context 
set-up procedure 2-3 
shutdown 2-8 
see tp stop command 
Signed on users 
see tp who command 


3-1, 


tp_command_table_ 


i=3 


TP subsystem (cont) 
source language 
command table compiler 
see tp cvsct command 
specific user requests 
startup 
see tp start command 
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Start_up exec com 2-6 
subroutines 3-1 
termination 


see tp io signoff command 
test modé 3-20, 3-21 
testing 2-9 
transaction control file (TCF) 
users 

see tp who command 
User_ids 2-2 


TP subsystem startup 2-7 


TP user 1-1 
tp_user command 


TP user identifier 
see TP_user_id 


tp.tef 
see transaction control file 


tp.tping 
see input queue 


tp.tpoutq 
see output queue 


TPR 


TPR languages 1-1 


COBOL 6-4 
FORTRAN 6-5 
PL/I 6-4 


tp_add_user command 2-6 
34 


weuenonee Aeadhine command 


tp_cancel command 
3-5 
tp_command table 

tp evset command 

tp display command table 
2-6 


tp_command table $ 
‘See command table: 


tp_cvset command 3-28 
tp_display command table 3-31 
tp_display_current_xens command 
3-32 
3-33 
3-34 
3-7 
2-4, 6-3 


tp_display input queue 
tp_display master table 
tp_display output queue 
tp_get_xen_status command 
tp_init_database.ec 2-1, 
3-19 


tp_io_cancel command 


tp_io enter _test_mode command 
3-20 


tp_io_exit_test_mode command 
3-21 


2-10, 


tp_io_get_xen_status command 3-22 


see transaction processing routine 


3-6 


2-10, 
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tp_io list_pending requests command 


tp_io_signoff command 3-24 
tp_io_start command 2-9, 3-25 
tp_io_who command 3-26 

tp_list_ pending requests command 3-8 
tp_master_ table 2-1 


tp_master table $ 
See master table 


tp_meters command 2-8, 3-35 
tp_meter_table_ 2-3 
tp_person_name table _ 2-1, 2-6 


tp_person_name_ table $see person-name 


table 
tp_pre_create exec_com 2-3, 2-4, 2-6, 
tp_ reset xcn_num command 3-37 


tp_rollback transaction_ subroutine 
3-13, 6-6 


tp_shrink_q command 2-8, 3-37, 3-38 


tp_start command 2-7, 3-9 
tp_start_command 2-7 


tp_start_up.ec 2-1 


tp_stop command 2-8, 3-10 


tp_user command 3-40 


TP_user_id 3-11, 3-17, 3-18, 3-26 
tp_verify_transaction_ subroutine 
3-14, 6-6 


tp_who command 3-11 


tp_worker_init_tcf command 3-15 


tp_worker_start command 2-9, 3-16 
transact operation 
see transaction_call command 
transaction 1-1 
aborting 
see tp rollback transaction 
subroutine = 
not completed 
see tp io list pending requests 
command — a 
see tp list pending requests 
command = 
removing 
see tp cancel command 
see tp io cancel command 
roll back ~ 
see tp _io_enter_test_mode command 
start worker process ~— 
see tp _worker_start command 
status — 
see tp get xen command 
see tp_io_get_xcn_status command 


transaction control file (TCF) 
2-3, 2-9, 3-15, 4-2 
attaching 
see tp worker init tcf command 
entries 4-2 — ~ 
entry 4-4 


oa; 


unrecoverable condition 


transaction control file (TCF) (cont) 
I/O switch 4-2, 4-4, 4-7 
opening 
see tp worker init tef command 
transaction status 4-5, 4-9 


transaction failure condition 4-6 


transaction number 1-6 


transaction processing 
see TP subsystem 


transaction processing routine (TPR) 


1<1, 1-8, 1-6, 2-6, 3-13, 3-14, 
3-35, 4-1, a= 1, 6-5 
input/output 6-2 
writing 6-1 


transaction processing subsystem 
see TP subsystem 


transactions currently displayed 3-6 
transaction_call command 4-4 
transaction _call_ subroutine 4-7 
transaction call_$assign entry 4-7 
transaction call_$commit entry 4-7 
transaction cali $number entry 4-8 
transaction call $rollback entry 4-8 


tramnann + 
vi Gdivavyu 


ion call $status ¢ Nad 


transaction call $transact entry 4-11 


unprocessed transactions 
see tp io list pending requests 
command — 7 
see tp_list_pending requests command 


5-1 


user transaction 1-4 


User ids 1-4, 2-2, 2-3, 2-6 
V 
vfile_ 
attaching files 6-5 


4o4 
4-7 


transaction interfaces 
transaction mechanism 


vfile transaction 
commitment 4-1, 4-4, 4-7 
executing command line 4-6, 4-11 
number 4-1, 4-2, 4-4, 4-8 
number assignment 4-6 
rollback 4-1 
status 4-9 


termination 4-1 


W 
worker process 1-2, 1-4, 2-2, 2-7, 
2-9, 3-1, 6-1 
absin file 2-4 
commands 3-12 
see tp worker start command 
subroutines 3-12 


worker _start_up.absin 2-1 
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worker start_up.absin (cont) 
see worker process 
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